---
title: 'How to write guides for Prisma ORM'
metaTitle: 'How to write guides for Prisma ORM'
description: 'Learn how to write clear, consistent, and helpful guides for Prisma ORM documentation'
sidebar_label: 'Guide writing guide'
completion_time: '5 min'
image: '/img/guides/guide-writing-guide-cover.png'
community_section: true
---

## Introduction

This guide shows you how to write guides for Prisma ORM documentation. It covers the required structure, formatting, and style conventions to ensure consistency across all guides. You'll learn about frontmatter requirements, section organization, and writing style.

## Prerequisites

Before writing a guide, make sure you have:

- A clear understanding of the topic you're writing about
- Access to the Prisma documentation repository
- Familiarity with Markdown and MDX
- Knowledge of the target audience for your guide

## Guide structure

### Required frontmatter

Every guide must include the following frontmatter at the top of the file:

```mdx
---
title: 'How to [do something] with Prisma ORM'
metaTitle: 'How to [do something] with Prisma ORM'
description: 'Learn how to [do something] with Prisma ORM'
sidebar_label: '[Concise Label]'
image: '/img/guides/[guide-name]-cover.png'
community_section: true
---
```

- `title`: Should be action-oriented and start with "How to"
- `metaTitle`: Usually matches the title, used for SEO
- `description`: A one-sentence summary starting with "Learn how to", used for SEO
- `sidebar_label`: A concise label for the sidebar navigation
- `image`: A unique header image for social media sharing (coordinate with the design team)

All frontmatter fields should be in sentence case, except for `image`.

### Required sections

1. **Introduction**
   - Brief overview of what the guide covers
   - What the reader will learn/accomplish
   - Link to any example repositories or related resources

2. **Prerequisites**
   - Required software/tools with version numbers
   - Required knowledge/experience
   - Any necessary accounts or access

3. **Main content sections**
   - Numbered steps for procedural guides (e.g., "1. Set up the project")
   - Clear hierarchy with H2 (`##`) for main sections
   - H3 (`###`) for subsections
   - Each step should build on previous steps

4. **Next steps**
   - What to do after completing the guide
   - Related guides or documentation
   - Links to additional resources
   - Community resources (e.g., Discord)

## Writing style and voice

### General principles

- Write in a clear, conversational tone
- Use active voice and present tense
- Address the reader directly using "you"
- Use first person plural ("we") when guiding the reader through steps
- Avoid jargon and explain technical terms
- Be concise but thorough

### Code examples

- Include complete, runnable code examples
- Use syntax highlighting with language specification
- Include file paths in code block metadata
- Use comments to explain complex parts
- Show both the problem and solution when applicable

Example:

```typescript file=src/index.ts
// Import required dependencies
import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

// Initialize adapter
const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
})

// Initialize Prisma Client
const prisma = new PrismaClient({
  adapter,
})
```

### Formatting conventions

- Use backticks for:
  - File names: \`schema.prisma\`
  - Directory names: \`prisma/\`
  - Code elements: \`PrismaClient\`
  - Commands: \`npx prisma generate\`
- Use [admonitions](https://docusaurus.io/docs/markdown-features/admonitions) for important notes, warnings, tips, etc.:
  ```mdx
  :::note
  Important information goes here
  :::
  ```
- Use proper heading hierarchy (never skip levels)
- Include line numbers in longer code blocks
- Use tabbed content for alternative approaches

## Examples from existing guides

### Migration guide format

Migration guides follow a specific pattern, as seen in guides like [Migrate from Sequelize](/guides/migrate-from-sequelize) and [Migrate from Mongoose](/guides/migrate-from-mongoose):

1. Clear introduction explaining the migration path
2. Prerequisites specific to both ORMs
3. Step-by-step migration process
4. Code comparison between ORMs
5. Practical examples of common operations

### Integration guide format

Integration guides, like [Using Prisma ORM with Cloudflare D1](/guides/cloudflare-d1), focus on:

1. Setup and configuration
2. Platform-specific considerations
3. Step-by-step implementation
4. Deployment instructions
5. Platform-specific best practices

## Best practices

1. **Keep it focused**
   - Each guide should cover one main topic
   - Break complex topics into multiple guides
   - Link to related guides instead of duplicating content

2. **Show don't tell**
   - Include practical, real-world examples
   - Provide complete, working code samples
   - Explain why certain approaches are recommended

3. **Consider the context**
   - Explain prerequisites clearly
   - Don't assume prior knowledge
   - Link to foundational concepts within or outside of our docs when needed

4. **Maintain consistency**
   - Follow the established guide structure
   - Use consistent terminology
   - Match the style of existing guides

5. **Think about maintenance**
   - Use version numbers where appropriate
   - Avoid time-sensitive references
   - Consider future updates when structuring content

## Template

This is a template for a guide. It is to standarize the format of the guide, the prisma integration, and make it easier to write a guide.

Before you submit a PR, run through the checklist and make sure to read all Dev Note's and remove them.

To get the guide into the sidebar, you need to add the following to the `sidebars.ts` file:

```typescript file=sidebars.ts
{
  type: "category",
  label: "Framework Guides",
  collapsed: false,
  collapsible: false,
  items: [
    "guides/turborepo",
    "guides/nextjs",
    "guides/nuxt",
    "guides/tanstack-start",
    "guides/react-router-7",
    "guides/solid-start",
    "guides/sveltekit",
    //add-next-line
    "guides/__________",
  ].sort(),
},
```

Copy and paste the template into a new `.mdx` file:

````markdown
---
title: 'How to use Prisma ORM with __________'
metaTitle: 'How to use Prisma ORM and Prisma Postgres with __________'
description: 'Learn how to use Prisma ORM in a __________ app'
sidebar_label: '__________ with Prisma'
image: '/img/guides/prisma-__________-cover.png'
completion_time: '15 min'
community_section: true
---

:::warning

DEVELOPER CHECKLIST - Remove upon completion

- [ ] `CTRL or CMD + F` to find 10 `_`'s and replace them with the framework name.

- [ ] Provide a brief overview of the guide's purpose and the benefits of integrating Prisma ORM with the specified framework.

- [ ] Link to the official documentation of the framework upon its first mention in the Introduction section.

- [ ] List all necessary or recommended prerequisites, including specific software versions and any required accounts or services.

- [ ] Name project *<u>framework</u>*-prisma (ie. *<u>__________</u>*-prisma)

- [ ] Project creation options should be detailed in an info admonition in this format:
```markdown
markdown - *Which package manager would you like to use?* `npm` 
```
- [ ] Ensure the appropriate admonitions (note, warning, tip) are used for important information.

- [ ] Include links to related guides and resources throughout the content.

- [ ] Instead of using `we, we'll, ours, etc.` use `you, you'll, yours, etc.`

- [ ] All lines ending before a code block should end with a colon (This one -> `:`)

:::

## Introduction

Prisma ORM streamlines database access with type-safe queries, and when paired with [__________](https://example.com/), it creates a...

:::warning

***DEV NOTE:*** Above, briefly explain the benefits of using Prisma ORM with the specified framework after `it creates a...`

:::

In this guide, you'll learn to integrate Prisma ORM with a Prisma Postgres database in a __________ project from scratch. You can find a complete example of this guide on [GitHub](https://github.com/prisma/prisma-examples/tree/latest/orm/__________).

## Prerequisites
- [Node.js 20+](https://nodejs.org)

## 1. Set up your project

## 2. Install and Configure Prisma

### 2.1. Install dependencies

To get started with Prisma, you'll need to install a few dependencies:

```terminal
npm install prisma tsx @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg dotenv pg
```

:::info

If you are using a different database provider (MySQL, SQL Server, SQLite), install the corresponding driver adapter package instead of `@prisma/adapter-pg`. For more information, see [Database drivers](/orm/overview/databases/database-drivers).

:::

Once installed, initialize Prisma in your project:

:::warning
***DEV NOTE:*** Make sure you update the output path accordingly with the framework (ie. Next.js is `../app/generated/prisma`). and follow through with the proper import paths going forward. This template will be using `../generated/prisma`.
:::

```terminal
npx prisma init --db --output ../generated/prisma
```
:::info
You'll need to answer a few questions while setting up your Prisma Postgres database. Select the region closest to your location and a memorable name for your database like "My __________ Project"
:::

This will create:

- A `prisma` directory with a `schema.prisma` file.
- A Prisma Postgres database.
- A `.env` file containing the `DATABASE_URL` at the project root.
- An `output` directory for the generated Prisma Client as `__________/generated/prisma`.

### 2.2. Define your Prisma Schema

In the `prisma/schema.prisma` file, add the following models:

:::warning

***DEV NOTE:*** If using Vite, the generator client should not include `-js` in the provider:

```prisma file=prisma/schema.prisma
generator client {
	//edit-next-line
  provider = "prisma-client"
  output   = "../generated/prisma"
}
```

In addition, update the text above this and add "*and change the generator to use the `prisma-client` provider*"

:::

```prisma file=prisma/schema.prisma
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

//add-start
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  authorId  Int
  author    User    @relation(fields: [authorId], references: [id])
}
//add-end
```

This creates two models: `User` and `Post`, with a one-to-many relationship between them.

### 2.3. Configure Prisma

Create a `prisma.config.ts` file in the root of your project with the following content:

```typescript file=prisma.config.ts
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});
```

:::note

You'll need to install the `dotenv` package to load environment variables:

```bash
npm install dotenv
```

:::

:::warning
***DEV NOTE:*** If your guide includes database seeding, you'll update this config file later to add the `seed` field in the migrations section. See the seeding section below for an example.
:::

### 2.4. Generate Prisma Client and run migrations

Now, run the following command to create the database tables and generate the Prisma Client:

```terminal
npx prisma migrate dev --name init
npx prisma generate
```
### 2.5. Seed the database

Add some seed data to populate the database with sample users and posts.

Create a new file called `seed.ts` in the `prisma/` directory:

```typescript file=prisma/seed.ts
import { PrismaClient, Prisma } from "../generated/prisma";
import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
});

const prisma = new PrismaClient({
  adapter,
});

const userData: Prisma.UserCreateInput[] = [
  {
    name: "Alice",
    email: "alice@prisma.io",
    posts: {
      create: [
        {
          title: "Join the Prisma Discord",
          content: "https://pris.ly/discord",
          published: true,
        },
        {
          title: "Prisma on YouTube",
          content: "https://pris.ly/youtube",
        },
      ],
    },
  },
  {
    name: "Bob",
    email: "bob@prisma.io",
    posts: {
      create: [
        {
          title: "Follow Prisma on Twitter",
          content: "https://www.twitter.com/prisma",
          published: true,
        },
      ],
    },
  },
];

export async function main() {
  for (const u of userData) {
    await prisma.user.create({ data: u });
  }
}

main();
```

Create a `prisma.config.ts` file to configure Prisma with seeding:

```typescript file=prisma.config.ts
//add-start
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: `tsx prisma/seed.ts`,
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});
//add-end
```

Run the seed script:

```terminal
npx prisma db seed
```

And open Prisma Studio to inspect your data:

```terminal
npx prisma studio
```

## 3. Integrate Prisma into __________

### 3.1. Create a Prisma Client

Create a `/lib` directory and a `prisma.ts` file inside it. This file will be used to create and export your Prisma Client instance.

Set up the Prisma client like this:

```tsx file=src/lib/prisma.ts
import { PrismaClient } from "../generated/prisma";
import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
});

const prisma = new PrismaClient({
  adapter,
});

export default prisma;
```

:::warning
We recommend using a connection pooler (like [Prisma Accelerate](https://www.prisma.io/accelerate)) to manage database connections efficiently.

If you choose not to use one, **avoid** instantiating `PrismaClient` globally in long-lived environments. Instead, create and dispose of the client per request to prevent exhausting your database connections.
:::

### 3.2.

:::warning
***DEV NOTE:*** How do you implement prisma into the framework?
:::

You're done! You've just created a __________ app with Prisma ORM. Below are some next steps to explore, as well as some more resources to help you get started expanding your project.

## Next Steps

Now that you have a working __________ app connected to a Prisma Postgres database, you can:

- Extend your Prisma schema with more models and relationships
- Add create/update/delete routes and forms
- Explore authentication and validation
- Enable query caching with [Prisma Postgres](/postgres/database/caching) for better performance

### More Info

- [Prisma Documentation](/orm/overview/introduction)
- [__________ Documentation](https://example.com/)
````

## Next steps

After reading this guide, you can:

- Start writing your own guide using the provided structure
- Review existing guides for reference
- Request a unique header image for your guide
- Submit your guide for review

For more information:
- [Prisma documentation style guide](/about/style-guide)
- [Documentation components](/about/docs-components)